package com.szwistar.common.meta;

import java.lang.annotation.*;


/**
 * 针对对象属性字段的注解类
 * <p>此注解类的目的是对对象属性进行描述，可用于自动生成UI、智能规则事件过滤条件编辑等场景
 * @author 张勇 2018-3-21
 */
@Documented
@Target({ElementType.FIELD, ElementType.METHOD})
@Inherited
@Retention(RetentionPolicy.RUNTIME)
public @interface DefField {
    /**
     * 中文名称
     */
    String title();

    /**
     * 是一个 JS 的表达式字符串，返回一个布尔值，用于指示此字段在什么条件下有效。
     * <p>此 JS 表达式在进行 eval() 前，会定义以下变量，可在表达式中引用：
     * <li>me 表示此字段所在的对象本身；可通过它引用其它字段的值，实现条件判断，从而实现字段间的联动
     * <li>obj 表示一个对象，具体含义由用户自己定义
     * <p>默认值为 "true"，表示此字段有效
     */
    String enable() default "true";

    /**
     * 是否可写(可以更改)
     * <p>用法类似于 {@link #enable()}
     */
    String writable() default "true";

    /**
     * 是否必需(不能为空)
     * <p>用法类似于 {@link #enable()}
     */
    String required() default "false";

    /**
     * 所在的属性分组名
     * <p>组名可以用来对对象的多个字段进行分组显示/编辑，属于同一分组的字段，应放在一起显示/编辑
     * <p>组名支持多级分组，中间用 "/" 分开，如: "WiFi参数/AP", "WiFi参数/STA/固定IP" 等
     * <p>组名默认为空，表示默认分组
     * <p>组名用于 UI 界面自动生成时，各个分组中的字段如何组织和显示，由前端自己定义。如：1级分组用 TAB 页分开；2级分组用抽屉分开；...
     */
    String group() default "";

    /**
     * 字段界面显示/输入类型
     * <p>常用的类型如下：
     * <li>boolean 布尔值
     * <li>number 数字，rangeJson="[0,3]"，表示数字取值范围为 0~3
     * <li>string 字符串，rangeJson="[6,12]"，表示长度最小为6字符，最大为12字符
     * <li>password 密码，rangeJson="[6,12]"，表示长度最小为6字符，最大为12字符
     * <li>list 从字符串列表单选一个，并返回字符串，rangeJson="[\"按钮1\",\"按钮2\",\"按钮3\"]"
     * <li>listx 从字符串列表中可选多个，并返回字符串数组，rangeJson="[\"按钮1\",\"按钮2\",\"按钮3\"]"
     * <li>dict 从字典中选择一项，并返回其 key，rangeJson="[{"key":0,"name":\"中国\"},{"key":1,"name":\"美国\"}]"
     * <li>dictx 从字典中选择多项，并返回其 key 数组，rangeJson="[{"key":0,"name":\"中国\"},{"key":1,"name":\"美国\"}]"
     * <li>date 字符串表示的日期，如 "2023-10-12"
     * <li>time 字符串表示的时间，如 "13:45:24"
     * <li>datetime 字符串表示的日期和时间，如 "2023-10-12 13:45:24"
     * <li>ipv4 字符串表示的 IPv4 地址，如 "192.168.1.32"
     * <li>ipv4Info JSON 字符串表示的 3 个 IPv4 地址: [IP, MASK, GATEWAY]，如 '["192.168.1.32","255.255.255.0","192.168.1.1"]'
     */
    String uiType() default "string";

    /**
     * 取值范围定义(JSON 格式)，可做为字段编辑时的取值范围
     * <p>不同的 uiType 对应的 range 的定义也不同，具体见 {@link #uiType()}
     * 举例：
     * <li>JSON 转义字符串: uiType="dict", rangeJson="{\"GSM\":1,\"UMTS\":2,\"LTE\":3}"
     */
    String rangeJson() default "";

    /**
     * 取值范围定义(JavaScript 表达式)，可做为字段编辑时的取值范围
     * <p>此表达式在前端 eval() 的结果含义同 {@link #rangeJson()}
     * 举例：
     * <li>JavaScript代码: uiType="dict", rangeJs="{GSM:1,UMTS:2,LTE:3}"
     * <li>JavaScript代码: uiType="dict", rangeJs="ota.getRadioModes()"
     */
    String rangeJs() default "";

    /**
     * 数值的单位，可被做为字段值的显示单位，如: % ℃ ℉ ¥ $ dB dBm V mV A mA
     */
    String unit() default "";

    /**
     * 描述
     */
    String description() default "";
}
